WebSocket Provider

Real-time bidirectional communication for UTCP

The WebSocket provider enables bidirectional, real-time communication between agents and tools, making it ideal for applications that require persistent connections and low-latency data exchange such as chat systems, live data feeds, and collaborative applications.

Configuration

WebSocket providers are configured using the following JSON structure:

{
  "name": "realtime_chat_service",
  "provider_type": "websocket",
  "url": "wss://api.example.com/socket",
  "auth": {
    "auth_type": "api_key",
    "api_key": "YOUR_API_KEY",
    "var_name": "token"
  },
  "protocol": "chat-protocol-v1",
  "keep_alive": true
}

Configuration Fields

Field	Required	Description
`name`	Yes	Unique identifier for the provider
`provider_type`	Yes	Must be set to `"websocket"`
`url`	Yes	WebSocket URL (`ws://` or `wss://`)
`protocol`	No	WebSocket sub-protocol to use
`keep_alive`	No	Whether to keep the connection alive (default: `true`)
`auth`	No	Authentication configuration (if required)
`headers`	No	Additional HTTP headers to include in the WebSocket handshake
`header_fields`	No	List of input fields to be sent as request headers for the initial connection

Message Format

Messages sent over the WebSocket connection follow a standard format:

Request Messages

{
  "type": "call",
  "tool": "tool_name",
  "id": "unique_request_id",
  "params": {
    // Tool parameters go here
  }
}

Response Messages

{
  "type": "result",
  "id": "unique_request_id",
  "result": {
    // Tool result data goes here
  }
}

Authentication Options

WebSocket providers support several authentication methods:

API Key Authentication

{
  "auth": {
    "auth_type": "api_key",
    "api_key": "YOUR_API_KEY",
    "var_name": "token"
  }
}

Bearer Token Authentication

{
  "auth": {
    "auth_type": "bearer",
    "token": "YOUR_BEARER_TOKEN"
  }
}

Tool Discovery

Since WebSockets don't naturally support the request-response pattern needed for tool discovery, provide a separate HTTP endpoint (typically /utcp) that returns the tool definitions:

{
  "name": "realtime_chat_service",
  "provider_type": "websocket",
  "url": "wss://api.example.com/socket",
  "discovery_url": "https://api.example.com/utcp"
}

The discovery endpoint should return a UTCPManual object as described in the For Tool Providers section.

Examples

Real-time Chat Application

{
  "name": "chat_service",
  "provider_type": "websocket",
  "url": "wss://chat.example.com/socket",
  "protocol": "chat-protocol-v1",
  "auth": {
    "auth_type": "api_key",
    "api_key": "your_api_key",
    "var_name": "token"
  }
}

Live Data Feed

{
  "name": "market_data",
  "provider_type": "websocket",
  "url": "wss://markets.example.com/feed",
  "keep_alive": true,
  "auth": {
    "auth_type": "bearer",
    "token": "your_jwt_token"
  }
}